Improve handling of arrays in `@defer` and `@stream` payloads #12923

jerelmiller · 2025-09-15T22:04:18Z

Fixes issues where arrays returned in @defer payloads would maintain cached items when the defer array was shorter than the cached array. This change also affects @stream arrays so that when a @stream chunk is processed, it truncates the array to the length of the stream payload. This ensures the length of the final result equals the length of the server array, much like it would if a plain refetch were issued.

…rge behavior

…rging

…d/streamed lists

changeset-bot · 2025-09-15T22:04:22Z

🦋 Changeset detected

Latest commit: c496039

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

apollo-librarian · 2025-09-15T22:05:16Z

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: 65998f1ed1f52cf86e6a07cb
Build Logs: View logs

pkg-pr-new · 2025-09-15T22:05:49Z

npm i https://pkg.pr.new/apollographql/apollo-client/@apollo/client@12923

commit: c496039

jerelmiller · 2025-09-15T22:07:18Z

.changeset/cold-kiwis-give.md

@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor


I'm marking this as a minor change. While it does fix the array merging behavior, it's a big enough difference to warrant a minor.

jerelmiller · 2025-09-15T22:08:10Z

src/core/__tests__/client.watchQuery/defer20220824.test.ts

  expect(outgoingRequestSpy).toHaveBeenCalledTimes(2);
 });
+
+it.each([["cache-first"], ["no-cache"]] as const)(


These were added from #11374 (with some tweaks)

jerelmiller · 2025-09-15T22:08:27Z

src/core/__tests__/client.watchQuery/deferGraphQL17Alpha9.test.ts

  expect(outgoingRequestSpy).toHaveBeenCalledTimes(2);
 });
+
+it.each([["cache-first"], ["no-cache"]] as const)(


Added from #11374 (with some tweaks)

jerelmiller · 2025-09-15T22:10:33Z

src/core/__tests__/client.watchQuery/streamDefer20220824.test.ts

+      Query: {
+        fields: {
+          friendList: {
+            merge: (existing = [], incoming, { field }) => {


Should we consider exposing a utility function or helper of some kind to do this kind of thing? At the very least, we probably want to put something in our docs along with @stream that describes how to do this in your own code. This demonstrates that you can maintain the original cached items when using stream instead of default overwriting the array.

Let's document it first and figure out the perfect helper later.

jerelmiller · 2025-09-15T22:11:21Z

src/incremental/handlers/__tests__/defer20220824/stream.test.ts

        friendList: [
          { name: "Luke", id: "1" },
          { name: "Han", id: "2" },
-          { name: "Leia Cached", id: "3" },


This behavior will now rely on a merge function to keep the cached item if the user wishes.

jerelmiller · 2025-09-15T22:24:53Z

src/react/hooks/__tests__/useQuery/streamGraphQL17Alpha9.test.tsx

+        Query: {
+          fields: {
+            friendList: {
+              merge: (_, incoming) => incoming,


I added this here to silence the warning about data loss, but I think this might happen a lot with @stream since fetches against a @stream field will naturally return a shorter list than already-cached lists since the list is streamed in over time.

Should we consider muting the warning for @stream fields like we do for @defer? Or should we recommend adding these type policies to explicitly opt into the @stream behavior?

I'm more confused as why this would warrant a data loss warning in the first place, at least with the output we have here. It's just overwriting a reference array with a shorter reference array, without any real data loss?

console.warn Cache data may be lost when replacing the friendList field of a Query object. This could cause additional (usually avoidable) network requests to fetch data that were otherwise cached. To address this problem (which is not a bug in Apollo Client), define a custom merge function for the Query.friendList field, so InMemoryCache can safely merge these objects: existing: [ { __ref: 'Friend:1' }, { __ref: 'Friend:2' }, { __ref: 'Friend:3' }, [length]: 3 ] incoming: [ { __ref: 'Friend:1' }, [length]: 1 ] For more information about these options, please refer to the documentation: * Ensuring entity objects have IDs: https://go.apollo.dev/c/generating-unique-identifiers * Defining custom merge functions: https://go.apollo.dev/c/merging-non-normalized-objects

Discussed in person. We want to silence the warning if the field has an @stream directive on it, otherwise every @stream field will require a field policy which feels broken.

jerelmiller · 2025-09-15T22:51:47Z

src/utilities/internal/DeepMerger.ts

+export class DeepMerger<TContextArgs extends any[] = any[]> {
  constructor(
-    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>
+    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>,


Since this is an internal class, I know we are free to update the API so with that in mind... should reconciler be moved to options instead? Its a bit awkward in places where we need arrayMerge but not reconciler since you have to pass undefined as the first argument.

Thoughts on changing it so we can do:

new DeepMerger({ arrayMerge: 'truncate' });

?

We use reconciler exactly once in the codebase, so it won't change things around a lot. What do you think about just making it an option?

phryneas · 2025-11-12T11:57:30Z

.changeset/cold-kiwis-give.md

+"@apollo/client": minor
+---
+
+Fix an issue where deferred payloads that reteurned arrays with fewer items than the original cached array would retain items from the cached array. This change includes `@stream` arrays where stream arrays replace the cached arrays.


Suggested change

Fix an issue where deferred payloads that reteurned arrays with fewer items than the original cached array would retain items from the cached array. This change includes `@stream` arrays where stream arrays replace the cached arrays.

Fix an issue where deferred payloads that returned arrays with fewer items than the original cached array would retain items from the cached array. This change includes `@stream` arrays where stream arrays replace the cached arrays.

phryneas · 2025-11-12T12:01:23Z

src/utilities/internal/DeepMerger.ts

+export class DeepMerger<TContextArgs extends any[] = any[]> {
  constructor(
-    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>
+    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>,


We use reconciler exactly once in the codebase, so it won't change things around a lot. What do you think about just making it an option?

phryneas · 2025-11-12T12:27:54Z

src/incremental/handlers/defer20220824.ts

+            if (isNumericKey) {
+              arrayMerge = "combine";
+            }


This feels like a workaround that might explode into our face in some way at some point - e.g. when we'd want to truncate deeply nested, but a parent is an array.

Alternative suggestion: WDTY about adding an atPath option into DeepMerger?
The arrayMerge strategy should then only apply at the exact level where the new source is being inserted, with everything else always being treated as combine - and we would also save creating all these deeply nested objects just for the sake of merging, which will be thrown away after the merge anyways.

phryneas · 2025-11-12T13:44:23Z

src/react/hooks/__tests__/useQuery/streamGraphQL17Alpha9.test.tsx

+        Query: {
+          fields: {
+            friendList: {
+              merge: (_, incoming) => incoming,


I'm more confused as why this would warrant a data loss warning in the first place, at least with the output we have here. It's just overwriting a reference array with a shorter reference array, without any real data loss?

console.warn Cache data may be lost when replacing the friendList field of a Query object. This could cause additional (usually avoidable) network requests to fetch data that were otherwise cached. To address this problem (which is not a bug in Apollo Client), define a custom merge function for the Query.friendList field, so InMemoryCache can safely merge these objects: existing: [ { __ref: 'Friend:1' }, { __ref: 'Friend:2' }, { __ref: 'Friend:3' }, [length]: 3 ] incoming: [ { __ref: 'Friend:1' }, [length]: 1 ] For more information about these options, please refer to the documentation: * Ensuring entity objects have IDs: https://go.apollo.dev/c/generating-unique-identifiers * Defining custom merge functions: https://go.apollo.dev/c/merging-non-normalized-objects

phryneas · 2025-11-12T13:47:52Z

src/react/hooks/__tests__/useSuspenseQuery/streamDefer20220824.test.tsx

-          { __typename: "Friend", id: "2", name: "Han" },
-          { __typename: "Friend", id: "3", name: "Leia" },
-        ],
+        friendList: [{ __typename: "Friend", id: "1", name: "Luke (refetch)" }],


Tbh, for a refetch it feels as if it should be merged, not truncated. Or even better, truncated on the last chunk, not the first one. But I don't have a good idea on how to make that distinction.

phryneas · 2025-11-12T13:51:14Z

src/core/__tests__/client.watchQuery/streamDefer20220824.test.ts

+      Query: {
+        fields: {
+          friendList: {
+            merge: (existing = [], incoming, { field }) => {


Let's document it first and figure out the perfect helper later.

jerelmiller added 23 commits September 12, 2025 17:12

Add array merge strategy to deep merger

1a2c04d

Default DeepMerger generic argument

92078c6

WIP truncate merge arrays

308702a

Check length before truncating

67161f6

Add another test for truncate merge

16bf7bc

Add past copies instead of copying twice

8442c84

Inline new merger

2f00a39

Move type to namespace

05f9085

Use dynamic array merge strategies

07567ef

Use property type for array merge

21a1928

Truncate arrays in defer20220824 handler

296dc9a

Update useBackgroundQuery tests to reflect updated nature on lists

156fa22

Combine array items if merging defer arrays

58b5269

Make graphql17Alpha9 more like Defer20220824 when determining arrayMe…

ede1476

…rge behavior

Update useSuspenseQuery stream tests with updated behavior of list me…

64d8536

…rging

Update spyOnConsole statement

5d7626a

Remove todo in useBackgroundQuery tests

32ad13a

Update useQuery stream tests

ac33578

Remove unneeded arg

3715a17

Add test to ensure custom merge function can be used to combine cache…

f9e176b

…d/streamed lists

Add changeset

2aa31c7

Update size limits

6dddd33

Add tests for refetches with defer arrays

1780c72

jerelmiller requested a review from phryneas September 15, 2025 22:04

jerelmiller mentioned this pull request Sep 15, 2025

Add test that shows a bug when merging deferred results for arrays. #11374

Closed

3 tasks

Fix changeset version type

f63c2b2

jerelmiller commented Sep 15, 2025

View reviewed changes

jerelmiller mentioned this pull request Sep 15, 2025

Add support for @stream #12918

Open

jerelmiller commented Sep 15, 2025

View reviewed changes

jerelmiller added 4 commits September 15, 2025 16:31

Print object as array in warning

dc712e7

Add changeset

01cace0

Update api report

31e405e

Fix tag mix in api report

c496039

jerelmiller commented Sep 15, 2025

View reviewed changes

This was referenced Sep 16, 2025

[3.9.5 but reproducible on latest] DeepMerger returns incorrect results when merging incremental arrays into existing data #12660

Open

Merging array in DeepMerger #11704

Open

jerelmiller force-pushed the jerel/stream-support branch from d071a61 to 096db02 Compare September 16, 2025 15:57

jerelmiller force-pushed the jerel/array-merge-strategy branch from 2a2fbc5 to 9b9d8aa Compare September 16, 2025 15:58

jerelmiller force-pushed the jerel/stream-support branch from 096db02 to b05df03 Compare September 16, 2025 16:02

jerelmiller force-pushed the jerel/array-merge-strategy branch 2 times, most recently from b41de5f to c496039 Compare September 16, 2025 16:32

github-actions bot mentioned this pull request Sep 17, 2025

Version Packages (alpha) #12928

Merged

phryneas reviewed Nov 12, 2025

View reviewed changes

	Fix an issue where deferred payloads that reteurned arrays with fewer items than the original cached array would retain items from the cached array. This change includes `@stream` arrays where stream arrays replace the cached arrays.
	Fix an issue where deferred payloads that returned arrays with fewer items than the original cached array would retain items from the cached array. This change includes `@stream` arrays where stream arrays replace the cached arrays.

Improve handling of arrays in @defer and @stream payloads #12923

Are you sure you want to change the base?

Improve handling of arrays in @defer and @stream payloads #12923

Conversation

jerelmiller commented Sep 15, 2025

Uh oh!

changeset-bot bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

apollo-librarian bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview has no changes

Uh oh!

pkg-pr-new bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Improve handling of arrays in `@defer` and `@stream` payloads #12923

Improve handling of arrays in `@defer` and `@stream` payloads #12923

changeset-bot bot commented Sep 15, 2025 •

edited

Loading

apollo-librarian bot commented Sep 15, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 15, 2025 •

edited

Loading